home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / SplitList.3 < prev    next >
Encoding:
Text File  |  1994-09-20  |  8.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. Tcl_SplitList(3)     Tcl Library Procedures
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      Tcl_SplitList,          Tcl_Merge,          Tcl_ScanElement,
  12.      Tcl_ConvertElement - manipulate Tcl lists
  13.  
  14. SYNOPSIS
  15.      #include <tcl.h>
  16.  
  17.      int
  18.      Tcl_SplitList(_i_n_t_e_r_p, _l_i_s_t, _a_r_g_c_P_t_r, _a_r_g_v_P_t_r)
  19.  
  20.      char *
  21.      Tcl_Merge(_a_r_g_c, _a_r_g_v)
  22.  
  23.      int
  24.      Tcl_ScanElement(_s_r_c, _f_l_a_g_s_P_t_r)
  25.  
  26.      int
  27.      Tcl_ConvertElement(_s_r_c, _d_s_t, _f_l_a_g_s)
  28.  
  29. ARGUMENTS
  30.      Tcl_Interp   *_i_n_t_e_r_p      (out)     Interpreter to  use  for
  31.                                          error reporting.
  32.  
  33.      char         *_l_i_s_t        (in)      Pointer to a string with
  34.                                          proper list structure.
  35.  
  36.      int          *_a_r_g_c_P_t_r     (out)     Filled in with number of
  37.                                          elements in _l_i_s_t.
  38.  
  39.      char         ***_a_r_g_v_P_t_r   (out)     *_a_r_g_v_P_t_r will be  filled
  40.                                          in  with  the address of
  41.                                          an array of pointers  to
  42.                                          the strings that are the
  43.                                          extracted  elements   of
  44.                                          _l_i_s_t.    There  will  be
  45.                                          *_a_r_g_c_P_t_r  valid  entries
  46.                                          in  the  array, followed
  47.                                          by a NULL entry.
  48.  
  49.      int          _a_r_g_c         (in)      Number  of  elements  in
  50.                                          _a_r_g_v.
  51.  
  52.      char         **_a_r_g_v       (in)      Array  of   strings   to
  53.                                          merge  together  into  a
  54.                                          single    list.     Each
  55.                                          string   will  become  a
  56.                                          separate element of  the
  57.                                          list.
  58.  
  59.      char         *_s_r_c         (in)      String that is to become
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SplitList(3)     Tcl Library Procedures
  71.  
  72.  
  73.  
  74.                                          an element of a list.
  75.  
  76.      int          *_f_l_a_g_s_P_t_r    (in)      Pointer to word to  fill
  77.                                          in    with   information
  78.                                          about _s_r_c.  The value of
  79.                                          *_f_l_a_g_s_P_t_r must be passed
  80.                                          to Tcl_ConvertElement.
  81.  
  82.      char         *_d_s_t         (in)      Place to copy  converted
  83.                                          list element.  Must con-
  84.                                          tain  enough  characters
  85.                                          to     hold    converted
  86.                                          string.
  87.  
  88.      int          _f_l_a_g_s        (in)      Information  about  _s_r_c.
  89.                                          Must  be  value returned
  90.                                          by  previous   call   to
  91.                                          Tcl_ScanElement,  possi-
  92.                                          bly      OR-ed      with
  93.                                          TCL_DONT_USE_BRACES.
  94. _________________________________________________________________
  95.  
  96.  
  97. DESCRIPTION
  98.      These procedures may be used to disassemble  and  reassemble
  99.      Tcl  lists.  Tcl_SplitList breaks a list up into its consti-
  100.      tuent elements, returning an array of pointers to  the  ele-
  101.      ments using _a_r_g_c_P_t_r and _a_r_g_v_P_t_r.  While extracting the argu-
  102.      ments, Tcl_SplitList obeys the  usual  rules  for  backslash
  103.      substitutions  and braces.  The area of memory pointed to by
  104.      *_a_r_g_v_P_t_r is dynamically allocated;  in addition to the array
  105.      of  pointers, it also holds copies of all the list elements.
  106.      It is the caller's responsibility to free  up  all  of  this
  107.      storage by calling
  108.  
  109.           free((char *) *_a_r_g_v_P_t_r)
  110.  
  111.      when the list elements are no longer needed.
  112.  
  113.      Tcl_SplitList normally returns TCL_OK, which means the  list
  114.      was  successfully  parsed.   If  there was a syntax error in
  115.      _l_i_s_t, then TCL_ERROR is  returned  and  _i_n_t_e_r_p->_r_e_s_u_l_t  will
  116.      point  to  an  error  message  describing  the  problem.  If
  117.      TCL_ERROR is  returned  then  no  memory  is  allocated  and
  118.      *_a_r_g_v_P_t_r is not modified.
  119.  
  120.      Tcl_Merge is the inverse of Tcl_SplitList:  it takes a  col-
  121.      lection  of  strings  given by _a_r_g_c and _a_r_g_v and generates a
  122.      result string that has proper list  structure.   This  means
  123.      that commands like index may be used to extract the original
  124.      elements again.  In addition, if the result of Tcl_Merge  is
  125.      passed  to Tcl_Eval, it will be parsed into _a_r_g_c words whose
  126.      values will be the  same  as  the  _a_r_g_v  strings  passed  to
  127.  
  128.  
  129.  
  130. Tcl                                                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SplitList(3)     Tcl Library Procedures
  137.  
  138.  
  139.  
  140.      Tcl_Merge.   Tcl_Merge  will  modify  the list elements with
  141.      braces and/or backslashes in order  to  produce  proper  Tcl
  142.      list  structure.  The result string is dynamically allocated
  143.      using malloc();  the  caller  must  eventually  release  the
  144.      space using free().
  145.  
  146.      If the result of Tcl_Merge is passed to  Tcl_SplitList,  the
  147.      elements  returned  by  Tcl_SplitList  will  be identical to
  148.      those passed into Tcl_Merge.  However, the converse  is  not
  149.      true:   if  Tcl_SplitList  is passed a given string, and the
  150.      resulting _a_r_g_c and _a_r_g_v are passed to Tcl_Merge, the result-
  151.      ing string may not be the same as the original string passed
  152.      to  Tcl_SplitList.   This  is  because  Tcl_Merge  may   use
  153.      backslashes and braces differently than the original string.
  154.  
  155.      Tcl_ScanElement and Tcl_ConvertElement  are  the  procedures
  156.      that  do all of the real work of Tcl_Merge.  Tcl_ScanElement
  157.      scans its _s_r_c argument and determines how to use backslashes
  158.      and braces when converting it to a list element.  It returns
  159.      an overestimate of the  number  of  characters  required  to
  160.      represent  _s_r_c  as a list element, and it stores information
  161.      in *_f_l_a_g_s_P_t_r that is needed by Tcl_ConvertElement.
  162.  
  163.      Tcl_ConvertElement   is    a    companion    procedure    to
  164.      Tcl_ScanElement.   It  does  the actual work of converting a
  165.      string to a list element.  Its _f_l_a_g_s argument  must  be  the
  166.      same    as    the   value   returned   by   Tcl_ScanElement.
  167.      Tcl_ConvertElement writes a proper list  element  to  memory
  168.      starting  at *_d_s_t and returns a count of the total number of
  169.      characters written, which will be no more  than  the  result
  170.      returned  by Tcl_ScanElement.  Tcl_ConvertElement writes out
  171.      only the actual list element without any leading or trailing
  172.      spaces:  it  is  up  to the caller to include spaces between
  173.      adjacent list elements.
  174.  
  175.      Tcl_ConvertElement uses one of two different  approaches  to
  176.      handle the special characters in _s_r_c.  Wherever possible, it
  177.      handles special characters by surrounding  the  string  with
  178.      braces.   This  produces  clean-looking output, but can't be
  179.      used in some situations, such as when _s_r_c contains unmatched
  180.      braces.   In  these  situations,  Tcl_ConvertElement handles
  181.      special characters by  generating  backslash  sequences  for
  182.      them.   The  caller may insist on the second approach by OR-
  183.      ing  the  flag  value  returned  by   Tcl_ScanElement   with
  184.      TCL_DONT_USE_BRACES.   Although  this will produce an uglier
  185.      result, it is useful in some  special  situations,  such  as
  186.      when  Tcl_ConvertElement is being used to generate a portion
  187.      of an argument for a Tcl command.  In this case, surrounding
  188.      _s_r_c  with  curly  braces  would  cause the command not to be
  189.      parsed correctly.
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tcl_SplitList(3)     Tcl Library Procedures
  203.  
  204.  
  205.  
  206. KEYWORDS
  207.      backslash, convert, element, list, merge, split, strings
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Tcl                                                             4
  262.  
  263.  
  264.  
  265.